.\" Man page generated from reStructuredText.
.
.TH "CRUSHTOOL" "8" "Mar 12, 2022" "dev" "Ceph"
.SH NAME
crushtool \- CRUSH map manipulation tool
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH 提纲
.nf
\fBcrushtool\fP ( \-d \fImap\fP | \-c \fImap.txt\fP | \-\-build \-\-num_osds \fInumosds\fP
\fIlayer1\fP \fI\&...\fP | \-\-test ) [ \-o \fIoutfile\fP ]
.fi
.sp
.SH 描述
.sp
\fBcrushtool\fP 是 CRUSH 图处理工具，它允许你创建、编译、反编译和测试 CRUSH 图。
.sp
CRUSH 是个伪随机数据分布算法，它能高效地把输入值
（它在 Ceph 上下文中对应归置组）映射到异构、结构化的分级设备图中。
此算法最初是在下面的论文（虽说已改进过了）中详细描述的：
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
http://www.ssrc.ucsc.edu/Papers/weil\-sc06.pdf
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
此工具有四种操作模式。
.INDENT 0.0
.TP
.B \-\-compile|\-c map.txt
把纯文本 map.txt 编译为二进制图文件。
.UNINDENT
.INDENT 0.0
.TP
.B \-\-decompile|\-d map
接受已编译的图，
并把它反编译为适合编辑的纯文本源文件。
.UNINDENT
.INDENT 0.0
.TP
.B \-\-build \-\-num_osds {num\-osds} layer1 ...
将用指定分级结构创建图。
详细解释见下文。
.UNINDENT
.INDENT 0.0
.TP
.B \-\-test
运行 CRUSH 模拟映射，参数是一系列输入值
\fB[\-\-min\-x,\-\-max\-x]\fP （默认是 \fB[0,1023]\fP ），
这个参数可当作是模拟的归置组。
详细解释见下文。
.UNINDENT
.sp
不像其它 Ceph 工具， \fBcrushtool\fP 不接受命令行输入的像
\fB\-\-debug\-crush\fP 这样的通用选项；
却可以通过 CEPH_ARGS 环境变量提供。例如，
可以这样压制 CRUSH 子系统的所有输出：
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
CEPH_ARGS="\-\-debug\-crush 0" crushtool ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SH 用 --TEST 进行测试
.sp
测试模式会采用输入 crush 图（用 \fB\-i map\fP 指定的），
并模拟 CRUSH 映射或随机放置（若设置了 \fB\-\-simulate\fP ）。
完成后可创建两种报告：
1) \fB\-\-show\-...\fP 选项会把人类可读的信息输出到标准错误；
2) \fB\-\-output\-csv\fP 选项会创建 CSV 文件，具体文档可在
\fB\-\-help\-output\fP 选项中见到。
.sp
注：每个归置组（ PG ）都有一个整数 ID ，可用 \fBceph pg dump\fP 获取
（例如 PG 2.2f 意思是存储池 id 为 2 ， PG id 为 32）。
存储池和 PG 的 ID 用一个函数连结成一个值，
然后传递给 CRUSH 就可以映射到一组 OSD 。
crushtool 不知道什么是 PG 或存储池，
它只是对 \fB[\-\-min\-x,\-\-max\-x]\fP 范围内的取值进行模拟映射。
.INDENT 0.0
.TP
.B \-\-show\-statistics
显示分布情况的摘要，例如：
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
rule 1 (metadata) num_rep 5 result size == 5:    1024/1024
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
在如上输出中，规则 \fB1\fP 名字为 \fBmetadata\fP ，
在试图把 \fB1024\fP 个值映射为 \fBnum_rep 5\fP 个副本时，
最终成功地映射到了 \fBresult size == 5\fP 个设备。
如果它最终没能输出映射，假设还需提高\fB尝试\fP次数），
就会显示失败情况。比如：
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
rule 1 (metadata) num_rep 10 result size == 8:   4/1024
rule 1 (metadata) num_rep 10 result size == 9:   93/1024
rule 1 (metadata) num_rep 10 result size == 10:  927/1024
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
以上表明，虽然要求的副本数是 \fBnum_rep 10\fP ，
但是 \fB1024\fP 个值中只有 \fB4\fP 个（ \fB4/1024\fP ）映射到了
\fBresult size == 8\fP 个设备。
.UNINDENT
.INDENT 0.0
.TP
.B \-\-show\-mappings
显示 \fB[\-\-min\-x,\-\-max\-x]\fP 范围内每个值的映射，
例如：
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
CRUSH rule 1 x 24 [11,6]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
显示了值 \fB24\fP 被规则 \fB1\fP 映射到了设备 \fB[11,6]\fP 。
.UNINDENT
.INDENT 0.0
.TP
.B \-\-show\-bad\-mappings
查看哪个值的映射数量没达到要求，
例如：
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
bad mapping rule 1 x 781 num_rep 7 result [8,10,2,11,6,9]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
表明规则 \fB1\fP 要求映射到 \fB7\fP 个设备，实际上只映射了六个：
\fB[8,10,2,11,6,9]\fP 。
.UNINDENT
.INDENT 0.0
.TP
.B \-\-show\-utilization
显示每个设备的期望和实际利用率，各种数量的副本也计算在内。例如：
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
device 0: stored : 951      expected : 853.333
device 1: stored : 963      expected : 853.333
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
表明设备 \fB0\fP 实际存储了 \fB951\fP 个值，本来期望存储 \fB853\fP
个。隐含了 \fB\-\-show\-statistics\fP 。
.UNINDENT
.INDENT 0.0
.TP
.B \-\-show\-utilization\-all
显示结果与 \fB\-\-show\-utilization\fP 相同，
只是不剔除权重为 0 的设备。
隐含了 \fB\-\-show\-statistics\fP 。
.UNINDENT
.INDENT 0.0
.TP
.B \-\-show\-choose\-tries
显示要尝试多少次才能映射到设备。例如：
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
0:     95224
1:      3745
2:      2225
\&..
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
表明有 \fB95224\fP 次映射没重试就成功了，
\fB3745\fP 次映射尝试一次后成功，等等。
显示的最大行数与 \fB\-\-set\-choose\-total\-tries\fP 选项相同。
.UNINDENT
.INDENT 0.0
.TP
.B \-\-output\-csv
在当前目录内创建 CSV 文件用于保存输出信息，
具体请参考 \fB\-\-help\-output\fP 。
文件被命名为收集统计信息时涉及的规则，
比如使用了 metadata 规则时， CSV 文件将会是：
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
metadata\-absolute_weights.csv
metadata\-device_utilization.csv
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
文件的首行是本列的简单描述，例如：
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
metadata\-absolute_weights.csv
Device ID, Absolute Weight
0,1
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-\-output\-name NAME
指定了 \fB\-\-output\-csv\fP 选项时生成的文件名要加
\fBNAME\fP 前缀，例如 \fB\-\-output\-name FOO\fP 将创建这些文件：
.INDENT 7.0
.INDENT 3.5
.sp
.nf
.ft C
FOO\-metadata\-absolute_weights.csv
FOO\-metadata\-device_utilization.csv
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.sp
用 \fB\-\-set\-...\fP 选项可修改指定 crush 图内的可调值，
输入的 crush 图在内存中修改了。
例如：
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ crushtool \-i mymap \-\-test \-\-show\-bad\-mappings
bad mapping rule 1 x 781 num_rep 7 result [8,10,2,11,6,9]
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
上面的问题可通过增加 \fBchoose\-total\-tries\fP 来修正，如：
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ crushtool \-i mymap \-\-test \e
    \-\-show\-bad\-mappings \e
    \-\-set\-choose\-total\-tries 500
.ft P
.fi
.UNINDENT
.UNINDENT
.SH 用 --BUILD 构建新图
.sp
构建模式可生成一个分级图。
第一个参数指定了 CRUSH 分级结构中的设备（叶子）数量。
每一层都要描述如何分组前一层（或设备）。
.sp
各层都由如下要素组成：
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
bucket ( uniform | list | tree | straw | straw2 ) size
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
这里的 \fBbucket\fP 是本层桶的类型（如 "rack" ）。
构建时各桶名 \fBbucket\fP 后将追加一个惟一的数字
（如 "rack0" 、 "rack1" ……）。
.sp
第二个组件是桶类型：大多用 \fBstraw\fP 。
.sp
第三个组件是此桶的最大尺寸，为零时表示容量无限。
.SH 实例
.sp
假设我们有 2 行、每行有 2 个机架、每机架有 20 个节点、
每个节点有 4 个存储设备用于 OSD 守护进程，
这样的配置允许部署 320 个 OSD 守护进程。这里按照机架高 42U ，
节点都是 2U 高的，另外空余 2U 装机架交换机。
.sp
要如实展现我们的设备、节点、机架、行构成的分级结构，用此命令：
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ crushtool \-o crushmap \-\-build \-\-num_osds 320 \e
       node straw 4 \e
       rack straw 20 \e
       row straw 2 \e
       root straw 0
# id        weight  type name       reweight
\-87 320     root root
\-85 160             row row0
\-81 80                      rack rack0
\-1  4                               node node0
0   1                                       osd.0   1
1   1                                       osd.1   1
2   1                                       osd.2   1
3   1                                       osd.3   1
\-2  4                               node node1
4   1                                       osd.4   1
5   1                                       osd.5   1
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
这样就创建了 CRUSH 规则，以便测试。此规则与创建集群时默认创建的规则相同，
可用下面的方法编辑它们：
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
# 反编译
crushtool \-d crushmap \-o map.txt

# 编辑
emacs map.txt

# 重新编译
crushtool \-c map.txt \-o crushmap
.ft P
.fi
.UNINDENT
.UNINDENT
.SH 重新划类
.sp
\fIreclassify\fP 功能便于用户把较老的图
（维护着不同类型 OSD 的并行层次结构）转换为最新的 CRUSH 图，
这样才能用得上 \fIdevice class\fP 功能。更多信息见
\fI\%https://docs.ceph.com/en/latest/rados/operations/crush\-map\-edits/#migrating\-from\-a\-legacy\-ssd\-rule\-to\-device\-classes\fP 。
.SH --TEST 的输出实例
.sp
请到 \fI\%https://github.com/ceph/ceph/blob/master/src/test/cli/crushtool/set\-choose.t\fP
查看 \fBcrushtool \-\-test\fP 命令实例，及其输出。
.SH 使用范围
.sp
\fBcrushtool\fP 是 Ceph 的一部分，这是个伸缩力强、开源、分布式的存储系统，更多信息参见 \fI\%https://docs.ceph.com\fP 。
.SH 参考
.sp
ceph(8),
osdmaptool(8),
.SH 作者
.sp
John Wilkins 、 Sage Weil 、 Loic Dachary
.SH COPYRIGHT
2010-2014, Inktank Storage, Inc. and contributors. Licensed under Creative Commons Attribution Share Alike 3.0 (CC-BY-SA-3.0)
.\" Generated by docutils manpage writer.
.
